BBS in a Box 7/BBS in a Box - Macintosh - Volume VII (BBS in a Box) (January 1993).iso/Files/Bus/T-Z/Writers guide TXT

Text File | 1987-05-25 | 13KB | 260 lines

                        MACNEWS WRITERS’ GUIDE

                           February 15, 1987

  Editorial Profile

The MacNews Business Journal and Programming Journal are national
publications providing technical tutoring and current information.

1. Business Journal.  It may be assumed that these readers have virtually
no knowledge of the Macintosh outside of one or two specific programs. For
the most part these users are not interested in learning more about the
Macintosh itself but see it merely as a tool for doing a particular job.
They may subscribe to MacWorld, or occasionally buy it from a newsstand,
but, when they do read it, they do not go through it in detail but look
only at information that is relative to their individual function. In
short, the business user's main concern is with the business and doing work
efficiency and profitably.  Our job is to provide information that will
help with that objective.

2. Programming Journal.  There is a large group of Macintosh owners who are
interested in advancing their abilities in programming. For the most part
the members of this group have little or no knowledge of programming,
although some may have gained knowledge of BASIC or Pascal or even assembly
language on other computers.  They find Inside Macintosh to be generally
incomprehensible and MacTutor over their heads.  Articles for this group
must be written at a level they can understand, yet without insulting their
intelligence.  The wide variation in their knowledge and abilities must be
taken into account.  An article (or the first article of a series) should
start up front with a description of what the background of the reader  is
assumed to be.

  Submissions—General

A "feature article" should have a representative icon (which should be
submitted by the writer with the first article of a series), a very brief
synopsis of the article (should be prepared by the writer and submitted
with
each article), and, for the first article of a series, a brief biography.

Article Length-There are no specific minima or maxima. Generally, articles
of a tutorial nature tend to be more lengthy, and the typical length of an
article in either journal is from three to seven pages in the final format
(five to ten pages in MacWrite).  In most cases a short article (one to two
pages) must be exceptionally good to be acceptable.

  Format of Submittals

All submittals must be on Macintosh disks in MacWrite or MSWord. Unformated
text files and submissions by modem may be acceptable under some
circumstances, but please check with the editor first.

Type Face and size:  any type face and size is acceptable. Times 10 is
preferred.

Subheadings: Boldface Size 12. Do not underline subheadings.

Indentation: Do not indent paragraphs. Do not use tabs at all except in
source codes and tables.

Carriage returns:  Do not use except at the end of paragraphs; then use two.

Double space between sentences and after colons. Single space after commas.

Do not double space after italicized words.  It looks on the screen like
it's needed, but the LaserWriter takes care of it.

Hyphens: Except for words which are properly spelled with hyphens (for
example, state-of-the-art, self-complacent, ninety-nine), do not use.  When
a dash is needed for punctuation use shift-option- hyphen.

When referring to menu items, use all uppercase for primary menu titles and
capitalize the first letter of secondary items. For example, "From the FILE
menu Copy the text and then Paste it into the other document."

Please use Typesetter's quotes (both single and double).
These can be typed as follows:

(Beginning quote) Option-{
(Ending quote) Option-Shift-{
(Beginning single quote) Option-}
(Ending single quote) Option-Shift-}
Please use an ellipsis rather than three periods (...).  An ellipsis is
typed with Option-;

All the above can be converted by Search/Change in MacWrite or MS Word.

Source Code and Tables (as text)

Program listings and tables obviously require a carriage return at the end
of each line.  Additional carriage returns may be put in for blank lines as
needed.  Indentations (tabs)may be used, but they should be as small as
possible.  Keep lines as short as possible to avoid lines being
inadvertently  broken in final formating by PageMaker-for example, put
comments on a separate line rather on the same line as the code.

When stating a programming line or a lengthy command in the body of the
text, place it on a separate line to avoid confusion with the other text.
Source code should also be included in separate, clearly labeled files.
If tables are prepared on a spreadsheet such as Multiplan or Excel, they
should be pasted into MacWrite or MS Word (with tabs set for the columns -
please keep the tabs as close together as practical), MacPaint, or MacDraw,
enhanced if necessary, and saved as a PICT file if MacDraw.

Tables should also follow the guidelines for illustrations.

    Illustrations

There are two general types of figures.   One type illustrates a specific
point in the text and needs to be referenced by a figure number at that
point.  Don't count on a figure being adjacent  to the text that refers to
it; layout often prohibits that.  Don't refer to "the following figure" but
rather to Figure so and so.

The second type of figure illustrates the article in general or broad
points in the article.  These figures don't need to be referred to at all.
They can  just "float" (as in the National Geographic and most newspapers),
but, when they're done this way, they need lengthy, descriptive titles.

Screen dumps should be opened with MacPaint and trimmed of all unnecessary
parts.

Illustrations may be either MacPaint or PICT files. Illustrations may be
reduced and pasted into the MacWrite or MS Word text, but should also be
submitted, non-reduced, as separate files.

Object-oriented (PICT) graphics produce a better result than bit-mapped
graphics on the Laserwriter. Text in Object-oriented graphics is controlled
by the Laserwriter and, if not in Laserwriter fonts, will be converted to
Laserwriter fonts by the Laserwriter.  Text in bit-mapped graphics will be
printed as a figure by the Laserwriter.  Therefore, if you want a font to be
anything but Times, Helvetica, or Courier, use bit-mapped graphics.

Original ink drawings and photographs may be used, but prior arrangements
should be made with the editor.

   Reviews

Reviews of software, hardware, and books must be factual and thorough.
Discuss any defects, bugs, or other problems with the developer,
manufacturer, or publisher, and include their comments in the review.  The
following is a checklist of points that should be covered:

 Overview.  What, in general, is the product intended to do?  State who
makes it, and name any other products by the same people that the reader
might know about.  If possible, briefly compare to other products the reader
might be familiar with.  If you began using it recently, give your first
impressions of it.  Is the price remarkably high or low?  This section might
also contain an abstract of the rest of the review.

 Operation. Describe how to use the product in a logical order.  For
example, if you are reviewing an accounting program, start with a
description of data entry and conclude with the final reports generated by
the program.  Illustrate the discussion with screen dumps.  Assess the
learning curve for a new user.

 User Interface.  Describe how intuitive the product is, whether it makes
full use of the Mac's clipboard, uses standard menus, is generally easy or
difficult to use. Does it have a fully functional UNDO command?  Are there
keyboard equivalents for the menu commands?

 Copy Protection.  Describe any copy protection and any inconveniences it
may cause.  Would there be any problem installing it on a harddisk?  Is
there a limited number of installs?

 Documentation. Is the documentation well written and comprehensive?  Does
it make good use of illustrations, if appropriate?  How many pages are in
the manual?  Make note if the binding and printing are exceptionally bad or
good. Does it have a trouble-shooting section?

 Customer Service.  Is the company behind the product available for
technical assistance or resolution of problems?  Do they charge for it and,
if so, how much?  How easy or difficult is it to get to them?  Do they have
a toll-free telephone line?  Do they return calls?  What is their upgrade
policy?

 Conclusion or Summary. Your impressions of the product.  Summarize
outstanding strong and weak points.  Does it meet advertised claims?  Are
there significant omissions in the ads?  Do you recommend the product?  Do
you recommend it to a particular group or groups of users (for example,
people with hard disks, people with Mac Pluses)?  Do you recommend against
it for a particular group or groups?  If any defects are expected to be
corrected in future versions, or any enhancements made, so state.

 Wrapup. Give the version number that you reviewed. Give a listing of
products mentioned, who is responsible for them (names, addresses, phone
numbers), what their list prices are, and what machines they will run on
(128, 512, 512E, Mac+, Mac XL).

Organization - The above topics could serve as an outline, but the
organization of the review should be logical for the subject matter and the
topic.  Whether a discussion deserves to be a separate subtopic depends on
its importance and extent.  For example, documentation might be relatively
unimportant and covered under the topic on operations; or it might be of
such importance to need being addressed prior to the discussion of
operations. But, whatever the organization, make sure it is a logical and
cohesive progression throughout.

If several, similar products are reviewed, rate them against one another
both for various criteria and overall effectiveness.  Use tables for
comparison to the extent possible. You might do a separate review of each
product and then compare them at the end, or you might compare them as you
go.

Style

Use your personal style, but generally be less formal than a technical
report or even a newspaper article, while, at the same time, maintaining a
professional image.  Freely use the pronoun, "you". Use contractions.

Sentences should tend toward the short rather than the long and words
toward the simple and common rather than the complex.

Be wary of monotonous sentence structure.  Read back over what you've
written (there is no good writing, someone said, only good rewriting).  Do
most sentences begin with an independent introductory phrase?  Are most
sentences compound?  Do they tend to have the same rhythm?  They shouldn't.
Variety is the spice of writing as well as life.

Please use subheadings.  Use them every time there is a major shift in
thought, which is every few paragraphs in most writings.  Try to make them
eye-catching and amusing (but not silly).

Do not use boldface type to excess.  It catches the reader's attention with
great vigor-enough to distract from the reading.  And don't get carried away
with exclamation marks. Italics provide subtle emphasis for a word or a
phrase within a sentence, and they identify foreign languages and other
special cases.  Underlining makes text harder to read and should be avoided.

Be careful of humor and slang.  Both can be effective.  But both are very
difficult to use effectively.

Be aware of the level of your readers and neither put them down nor expect
too much from them.  Avoid (or at least be very careful of) such phrases as
"as everyone knows" and "now, wasn't that easy" (Everyone may not know
and maybe it wasn't easy for every reader.)  Don't put yourself down,
either-you are supposed to know what you are talking about or you wouldn't
be writing.  Don't act unsure of yourself.

It is a rare writer who doesn't need an outline to work from.  Without an
outline, an otherwise good writer will fail to have cohesion - each sentence
logically flowing into the next sentence; each paragraph logically flowing
into the next paragraph; each subtopic...and so on, from the first word of
the article to the last.  MORE, Acta, and IdeaLiner are examples of
excellent tools for helping organization.

Re-read your work.  Please!  If possible, let it get "cold" and read it
again.  Read it aloud - if it doesn't sound right aloud, it won't sound
right to the reader.

  General

Materials submitted will be returned only if a stamped, self-addressed
envelope is provided.  All published material becomes copyrighted property
of CJB Publishing, Inc. CJB Publishing, Inc., reserves the right to edit all
copy used.

- John Crane, General Editor                 CJB Publishing, Inc.
  EMail address: JOHN.CRANE on GEnie         P.O. Box 7068
  Telephone: [phone]                    Gainesville, FL 32605